PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / labyte.exe / LABYTE.DOC < prev next >

Wrap

Text File | 1992-05-08 | 19.3 KB | 482 lines

Memory Manager Version S1.1 One of the most difficult parts of programming in C is handling memory and its pointers. At least, that is what I found. To help me reduce these problems, I wrote LAByte. The functions provided are: 1. Handling the allocation of memory blocks, freeing the blocks, checking for memory corruption. 2. Provide a method of tracing the entrance into each function. NOTE: There are two separate traces maintained by the module. The first is for the memory functions and the second is for function tracing. Memory Processor Functions All calls are "traced". If an error occurs the trace table is written to a file named LATrace.LAC. Each of the function calls use the file name and line number. You may supply your own file name as a character pointer or use the __FILE__ symbol, likewise, you may use __LINE__ symbol for the line number. More on the trace later. Allocation of Memory Memory is allocated from the far heap. A far character pointer is returned pointing to the first usable byte of the block. The block is initialized to NULLs. prototype: char far *mem_getmain(char *File, int Line, char Fun1, char Fun2, int Size); char *File = A name that will point you to the module doing the getmain. You may use the __FILE__ symbol. int Line = A number representing the place in the module where the getmain was called. You may use the __LINE__ symbol. char Fun1 = These characters can be set to anything that will help char Fun2 point you in the right direction. I use the selection characters from the main menu and its pull down menu. int Size = The size of the memory block to be allocated. example: int Samp_Fun() { char far *Cnfg; Cnfg = mem_getmain(__FILE__, __LINE__, 'M', 'C', sizeof(CONFIG_DATA)); } Freeing A Memory Block When called, freemain will verify the integrity of the block passed, abending if it is not valid or freeing the block and returning to the calling return. This function can only be used to free memory blocks allocated by the getmain function because of the trace chain and block integrity header and trailer. prototype: int mem_freemain(char *File, int Line, char far *Pointer); char *File = A name that will point you to the module doing the getmain. You may use the __FILE__ symbol. int Line = A number representing the place in the module where the getmain was called. You may use the __LINE__ symbol. char far *Pointer = The pointer returned from the call to getmain. example: int Samp_Fun() { char far *Cnfg; mem_freemain(__FILE__, __LINE__, Cnfg); } Freeing Memory Blocks By A Function When called, cleanup will verify the integrity of all blocks on the chain where the passed function matches the char passed in Fun1 of the getmain, abending if an invalid is encountered or freeing the block and returning to the calling return. The reason for using cleanup is to eliminate the build up of unreleased memory as a function ends or as a quick and easy way to release all memory that was allocated to accomplish the function. prototype: int mem_cleanup(char *File, int Line, char Fun); char *File = A name that will point you to the module doing the getmain. You may use the __FILE__ symbol. int Line = A number representing the place in the module where the getmain was called. You may use the __LINE__ symbol. char Fun = The character passed in Fun1 of the getmain for the blocks to be released. example: int Samp_Fun() { mem_cleanup(__FILE__, __LINE__, 'M'); } Freeing All Memory Blocks When called, freeall will verify the integrity of all blocks on the chain, abending if invalid or freeing the blocks and returning to the calling return. prototype: int mem_freeall(char *File, int Line); char *File = A name that will point you to the module doing the getmain. You may use the __FILE__ symbol. int Line = A number representing the place in the module where the getmain was called. You may use the __LINE__ symbol. example: int Samp_Fun() { mem_freeall(__FILE__, __LINE__); } Memory Trace Entry Internal table Memory trace entries are allocated from the near heap as memory is allocated and added to the chain. The first trace entry address is saved in the anchor in LAByte.C named MemAnchor. typedef struct { int MemOK; /* Normally NULL but set to a value if an error is detected. see Error Codes below */ char MemMod[15]; /* File Name from getmain */ int MemLine; /* Line Number from getmain */ char MemFun; /* Fun1 from getmain */ char MemUse; /* Fun2 from getmain */ int MemLen; /* Length from getmain */ void far *MemAddr; /* Address of the memory block */ void *MemPrev; /* Address of the previous memory trace entry or the memory anchor in the header */ void *MemNext; /* Address of the next memory trace entry or null if this is the last entry on the chain */ } MEMTBL; LATrace.Lac File Entry (see Cancelling The Program below) M---5D8D:0004---0---main.c---25---M---C---365---5D75:0008---6C60:0004---0000:0000 ^-A ^-B ^-C ^-D ^-E ^-F ^-G ^-H ^-I ^-J ^-K A) Indicator showing this as a memory trace entry B) Address of this trace entry C) Error Code, see Error Codes below D) File Name E) Line Number F) Fun1 G) Fun2 H) Length of the memory block I) Address of the memory block J) Address of previous memory trace entry K) Address of next memory trace entry Error codes mem_freemain function 1 - There is no memory on the trace chain 2 - Can't find find the memory block on the chain 3 - The backward chain has been corrupted 4 - The forward chain has been corrupted 5 - The header of the memory block has been corrupted 6 - The trailer of the memory block has been corrupted mem_cleanup function 11 - The backward chain has been corrupted 12 - The header of a memory block has been corrupted 13 - The trailer of a memory block has been corrupted mem_freeall function 21 - The backward chain has been corrupted 22 - The header of a memory block has been corrupted 23 - The trailer of a memory block has been corrupted If the trailer of a memory block has been corrupted, error codes 6, 13 and 23, probably the definition of the area is larger than the memory block allocated. If the header is corrupted, error codes 5, 12 and 22, either the pointer has been changed, an array was improperly indexed or the previous area was overrun. For all other error codes, the memory trace chain has been corrupted in some fashion. Since the chain is allocated from the near heap, it should not be effected by your program. The problem could be caused If a pointer gets incorrectly set, if your program allocates areas from the near heap and corrupts it, or a program bug in LAByte. Function Tracing Functions Function tracing is an optional facility provided to determine the logic path through your program. Entries are placed in the trace table by calling function trace_entry. The trace table is anchored to the TraceTbl pointer in LAByte.C. The table, by default, is large enough to hold the last 100 entries. The size of the table can be changed by changing the define TRACEELEMS in the header. Because of performance, the trace table is held in memory until the program calls cancel_program. Cancel_program will be called if the memory processor functions detect an error or by your program. The trace table can be used during testing if a debugger is not the best answer to a particular problem. Also the trace can be left active in the production version of your program and your customer can upload the LATrace.Lac file to help you determine what occurred if your program should fail. I have NOT noticed any measurable performance impact by using this trace but some impact may be noticiable if it is called too often. But this should only be important in the production version of your program. If you need to create a "lot" of trace entries to debug a problem, the size of the trace table should be increased. Activating/Deactivating The Trace The trace logic can be activated or deactivated by the presence or absence of a define for LATRACE in LAByte.C. If present, the trace logic will be active. If LATRACE is absent, the trace table will not be allocated and calls to trace_entry will simply issue a return. Placing An Entry In The Trace Table I normally place a call to trace_entry as the first function of each of my functions and denote it with a type of E. Additional entries can be made to pinpoint problems or provide critical information if problems occur. prototype: void trace_entry(char Type, char *File, int Line) char Type = A character indicating the type of entry being made. char *File = A name that will point you to the module doing the getmain. You may use the __FILE__ symbol. int Line = A number representing the place in the module where the getmain was called. You may use the __LINE__ symbol. example: int Samp_Fun() { trace_entry('E', __FILE__, __LINE__); /* Trace Entry to Paragraph */ } Cancelling The Program And Dumping The Trace Table To A File This function is used to write both the memory trace table and the function trace table to LATrace.Lac. Even if the trace logic is disabled, the memory trace is written. This function does NOT return. There is a sample of LATrace.Lac provided. prototype: void cancel_prog(int ExitCode) int ExitCode = The code that is used to exit() the program after the trace table is written. example: int Samp_Fun() { cancel_prog(4); } Function Trace Entry Internal table Function trace entries are held in the TraceTbl as defined in the LAByte.C file. Room is provided for 100 entries by default but can be changed by changing the value of the TRACEELEMS define. #define TRACEELEMS 100 /* Size of trace table */ typedef struct { char Wrap; /* Indicates if table is wrapping */ int TracePtr; /* Pointer to the current entry */ struct { char Type; /* Type from trace_entry */ char Mod[15]; /* File from trace_entry */ int Line; /* Line from trace_entry */ } TraceElem[TRACEELEMS]; } TRACETBL; TRACETBL *TraceTbl = NULL; LATrace.Lac File Entry T---E---main.c---21 ^-A ^-B ^-C ^-D A) Indicator showing this as a function trace entry B) Type of trace_entry C) File of trace_entry D) Line of trace_entry Including In Your Program Place LAByte in the directory containing the other modules of your program. Include the module in your .Mak file or project file for the IDE. Change your program to call the routines and recompile the program. The LAByte header need only be included in LAByte.C. EXAMPLES OF USE 1. Storage overlay int stg_overlay() { char far *BadFld; BadFld = mem_getmain(__FILE__, _LINE__, '1', '2', 20); memset(BadFld, ' ', 30); } As a result of the memset, 10 bytes after the area allocated by the getmain are set to blanks. Depending on the use of these bytes the program could abort immediately, destroy data or function without any indication of the bug. The worse possible situation to occur is the last because the program may start abending after future changes are made and it will be almost impossible to relate the problem to the actual changes made. At least with the first two cases you are more apt to realize that a problem exists and take steps to correct it. When a free function is called, the corruption will be detected and the memory trace written to LATrace.Lac in the current directory. From the memory trace, the bad area can be determined an you will know where the area was allocated. From the function trace, you can determine the logic path that lead to the problem. 2. Program loop Finding a loop, which is why, in most cases, the system "locks up", can take a significant amount of time depending on the size and complexity of the logic. A good debugger helps. By including the trace_entry as the first function call of each function, to find a loop would look like this: Start the program executing under the debugger. When the program loops, break the code. Find the trace table in LAByte. Find the current entry. Scan backward to find the functions particpating in the loop. This will help you determine where to put the breakpoints in the debugger. LAByte is Shareware These routines are supplied on an as-is basis. We attempt to insure the accuracy of all our products. We do warrant that our software will not cause corruption of the information contained on the disk containing this product with the exception of that caused by hardware failures and that caused by a virus. We gaurantee that the software is virus free when uploaded to the original BBS but we cannot prevent its infection beyond that point. Because this module is provided as source code and not in executable form, it is unlikely to be infected. To avoid problems with viruses, we recommend that you use a good virus scanning product on this product and ALL software downloaded from a BBS. If you detect such a virus, we would like to know about it as soon as possible. The routines are written in Borland C++ from Borland International. The code is not object-oriented. You may freely copy and share this program as long as the routines and documentation are copied in their entirity. These routines are provided as a shareware product. You may use it without registering it for a reasonable time. The routines may not be included in any product, except for your own personal use, without registering it. If you should decide to register it, we will send you any corrections that may come to our attention. In addition, you will be made aware other products from the Programming Support Division of Logical Answers Corp as they become available. Registration Form: Name: _____________________________________________ Company: __________________________________________ Street: ___________________________________________ ___________________________________________ City: __________________ State: ____ Zip: _______ Product: PS01 Serial #: S1A0001 Where did you get your copy of this product? _________________________________________________ Do you want to be added to our mailing list? ______ Registration Fee: 15.00 Pa. Tax (6%): ______ Send your registration to: Logical Answers Corp. Programming Support Division P. O. Box 33 Brownstown, PA 17508 (717) 627-4181 ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of Public (software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. PsL cannot debug pro- programs over the telephone, though we can answer questions. Disks in the PsL are updated monthly, so if you did not get this disk directly from the PsL, you should be aware that the files in this set may no longer be the current versions. Also, if you got this disk from another vendor and are having prob- lems, be aware that some files may have become corrupted or lost by that vendor. Get a current, working disk from PsL. For a copy of the latest monthly software library newsletter and a list of the 4,000+ disks in the library, call or write Public (software) Library P.O.Box 35705 Houston, TX 77235-5705 Orders only: 1-800-2424-PSL MC/Visa/AmEx/Discover Outside of U.S. or in Texas or for general information, Call 1-713-524-6394 PsL also has an outstanding catalog for the Macintosh.